Workbench Design/WB Collection.iso/workbench werkzeuge/programmmanager/xtoolbox/xtoolbox.guide

Amigaguide Document | 1996-04-07 | 14KB | 273 lines

@DATABASE "Default"
@NODE "MAIN" "XToolBox - Main"
@NEXT "DISCLAIMER"
                               @{b}XTOOLBOX 1.1
                          released 30-October-1995 by
                               Dennis Doomen@{ub}
        @{b}Contents
        --------@{ub}
        @{"Disclaimer" LINK "DISCLAIMER"}          Make sure you read this.
        @{"Introduction" LINK "INTRODUCTION"}        What is it, and what can it do for you.
        @{"Requirements" LINK "REQUIREMENTS"}        What do you need.
        @{"Background" LINK "BACKGROUND"}          Why did I make this.
        @{"Getting Started" LINK "GETTINGSTARTED"}     How to create a ToolBox.
        @{"Bug Report" LINK "BUGREPORT"}          Bugs known and how to report them.
        @{"About The Author" LINK "AUTHOR"}    Who am I and how can you reach me.
        @{"Thanks To" LINK "THANKS"}           People who 'stood' beside me.
        @{"History" LINK "HISTORY"}             About the developing history.
        @{"To Do" LINK "TODO"}               Plans for the future
@ENDNODE
@NODE "DISCLAIMER" "XToolBox - Disclaimer"
@NEXT "INTRODUCTION"
@PREV "MAIN"
@TOC "MAIN"
@{b}DISCLAIMER
----------@{ub}
I've released @{i}XToolBox@{ui} under the concept of @{b}FREEWARE@{ub}, so everyone may use
it for whatever reasons they want. However, I am and will NOT be
responsible for any damage to your environment and system as a result of
the operation of @{i}XToolBox@{ui}. Nevertheless, I cannot imagine any situation
(except crashing) that could damage anything.
@ENDNODE
@NODE "INTRODUCTION" "XToolBox - Introduction"
@NEXT "REQUIREMENTS"
@PREV "DISCLAIMER"
@TOC "MAIN"
@{b}INTRODUCTION
------------@{ub}
@{i}XToolBox@{ui} is what I always wanted to have, a menutool like the WindowManager
you've maybe have seen once on a UNIX-station with XWindows. But if you didn't,
it consists of a window with a number of gadgets (BOOPSI objects). Whenever you
press one of them, a menuwindow will pop up displaying a list of items. While
holding down the left mousebutton you can move the mouse above one of these
items (this will be indicated by a bevelbox). Release the button, and the command
defined for that menuitem is executed.
Both the gadgets and the menuwindows are rendered in a nice 3D look and the
number of menus and menuitems is only limited by the size of your screen.
@{i}XToolBox@{ui} uses a new BOOPSI gadgetclass that I have created for it (see
@{"Background" LINK "BACKGROUND"}).
@ENDNODE
@NODE "REQUIREMENTS" "XToolBox - Requirements"
@NEXT "BACKGROUND"
@PREV "INTRODUCTION"
@TOC "MAIN"
@{b}REQUIREMENTS
------------@{ub}
@{i}XToolBox@{ui} requires the following resources:
  - Any Amiga that is equiped with Kickstart 3.0 or higher
  - The excellent @{b}Reqtools-library@{ub} (c) @{i}Nico Francois@{ui} (not included)
  - A good texteditor to design the menus
I could have made it OS2.0 compatible, but using 3.0+ functions made it a
little easier for me. However, if I get enough requests, I will try to
alter the program in order to make it OS2.0+ compatible.
@ENDNODE
@NODE "BACKGROUND" "XToolBox - Background"
@NEXT "GETTINGSTARTED"
@PREV "REQUIREMENTS"
@TOC "MAIN"
@{b}BACKGROUND
----------@{ub}
The reason for creating another menu-utility, was that I was not satisfied
with the current available ones. I was using @{b}ButtonMenu@{ub} by @{i}Oliver Roberts@{ui}
till now, but I wanted to have something like the WindowManager on UNIX
systems.
I previously was working on a music-database and I needed some custom
designed gadgets, so I created a shared library with some extensions to
Gadtools. I was aware of the @{b}BOOPSI@{ub} concept, but I simply did not have any
documentation, except for the RKRM-examples. But then I found some
GUI-libraries and saw what can be done with BOOPSI, so I decided to reserve
some time to study the concept. With the help of the RKRM-examples,
information from the Amiga-magazines and help from the Internet-community, I
succeeded in creating my first BOOPSI gadgetclass, the @{b}PopUpMenu@{ub}-gadgetclass.
If you've have looked at the buttons in the windowmenu, you should now that
every button (including it's menu) is a BOOPSI object from that class. I
will release the source for the class whenever I have finished it. The
reason for that is, that I want to add some extra features to it. But if
you are interested though, feel free to @{"contact" LINK "BUGREPORT"} me.
@ENDNODE
@NODE "GETTINGSTARTED" "XToolBox - Getting Started"
@NEXT "BUGREPORT"
@PREV "BACKGROUND"
@TOC "MAIN"
@{b}GETTING STARTED
---------------@{ub}
@{b}USAGE@{ub}
@{i}XToolBox@{ui} is driven by a configuration file supplied as a plain ASCII textfile.
This file contains keywords which define the various options of the @{i}XToolBox@{ui}
window. By default, @{i}XToolBox@{ui} opens the file @{i}s:XToolBox.menu@{ui}, but you
may specify any other file at the command line by entering:
    @{i}XToolBox <menufile>@{ui}
(Note that it autodetaches from the command line.)
To make thinks a little bit clearer, I've included an example menufile in the
package. I've also included a template which contains keywords only.
This configurationfile consists out of two parts, the environment definition and
the actual menu definition.
@{b}ENVIRONMENT@{ub}
The following keywords may (or must) be used in the first part of the
configuration; keywords are caseinsensitive and all strings must be enclosed by
quotes.
    @{b}TITLE@{ub} "title"       This keyword defines the title of the @{i}XToolBox@{ui} window on
                        the screen, e.g. TITLE "This is my ToolBox"
    @{b}XPOS@{ub} nnn            Defines the horizontal coordinate of the topleft edge of
                        the window, e.g. XPOS 0
    @{b}YPOS@{ub} nnn            Defines the vertical coordinate of the topleft edge of
                        the window, e.g. YPOS 14
    @{b}WIDTH@{ub} nnn           This keyword defines the width of the menugadgets used in
                        the @{i}XToolBox@{ui} window. The reason that you can't specify
                        the actual width of the window, is that this will result
                        in gadgets that sometimes are a little bit smaller and
                        sometimes a little bit wider. Example: WIDTH 60
    @{b}HEIGHT@{ub} nnn          The height of the menugadgets, e.g. HEIGHT 16
    @{b}SPACING@{ub} nnn         Defines the number of pixels between every menuitem in a
                        popup menu; defaults to 2.
    @{b}FONT@{ub} "name/size"    Specifies the font used for the gadgetlabel and the
                        menuitems in the popupmenu, e.g. FONT "topaz/8"
The following keywords are used to specify the colors for the gadgets and the
menus. They all must be supplied a hexadecimal number preceded by '@{i}0x@{ui}'.
The format is @{i}0xRRGGBB@{ui}, where @{i}RR@{ui} specifies the 8bit red value,
@{i}GG@{ui} the green value and @{i}BB@{ui} the blue value. For example
@{i}0xff03ff@{ui} means red=255, green=3 and blue=255.
    @{b}GADGETBACK@{ub}          Defines the gadgets' backgroundcolor.
    @{b}GADGETBRIGHT@{ub}        Defines the color of the bright edges of the gadgets.
    @{b}GADGETDARK@{ub}          Defines the color of the dark edges of the gadgets.
    @{b}MENUBACK@{ub}            Defines the menus' backgroundcolor.
    @{b}MENUBRIGHT@{ub}          Defines the color of the bright edges of the menus.
    @{b}MENUDARK@{ub}            Defines the color of the dark edges of the menus.
    @{b}TEXT@{ub}                Defines the textcolor of both the gadgetlabels and the
                        menuitems.
For example,
    @{i}GADGETBACK 0xbbb0bb@{ui}
Will make the gadgets' background light-grey.
@{b}MENU@{ub}
The menus are defined by three keywords: @{b}MENU@{ub}, @{b}ENTRY@{ub}, @{b}CMD@{ub}
The first one, @{b}MENU@{ub}, creates a menugadget labeled with the argument of this
keyword. For example,
    @{i}MENU "Utilities"@{ui}
will create one gadget labeled "Utilities". You may create as many menus as you
want, as long as they fit on the screen.
The next two keywords define the menuitem and its commandline, for example,
    @{i}ENTRY "XToolBox prefs"      CMD "edit s:XToolBox.menu"@{ui}
will create a menuitem in the current menu with name "XToolBox prefs". When
selected this will execute your favourite editor in order to change your default
@{i}XToolBox@{ui} configuration.
Make sure that all strings are enclosed by quotes and that every associating
ENTRY and CMD keyword are placed on the same line. Also make sure that there is an
empty line between the last ENTRY keyword and the next MENU keyword.
You may also insert a blank line in a menu by inserting the following line:
    @{i}ENTRY ""@{ui}
To summerize, another example:
    @{i}MENU "menu 1"
    ENTRY "item 1"      CMD "do something"
    ENTRY "item 2"      CMD "do something"
    ENTRY ""
    ENTRY "item 3"      CMD "do something"
    MENU "menu 2"
    ENTRY "item 1"      CMD "do something"
    ENTRY "item 2"      CMD "do something"
    ENTRY "item 3"      CMD "do something"
    ENTRY "item 4"      CMD "do something"@{ui}
Please look at the example included in the package.
@ENDNODE
@NODE "BUGREPORT" "XToolBox - Bug Report"
@NEXT "AUTHOR"
@PREV "GETTINGSTARTED"
@TOC "MAIN"
@{b}BUG REPORT
----------@{ub}
If you do find any bugs or you have any questions or problems, feel free to contact me.
In addition if you have any requests or suggestions don't hesitate to contact me also. This
will prevent me from adding features that aren't wanted actually (and saving a lot of my
time).
To contact me (e.g. to tell me that you are (happily) using my program) mail to
    @{i}[e-mail]@{ui} or
    @{i}[e-mail]@{ui}
or write to:
    @{i}Dennis Doomen
    Prinses Irenestraat 50
    6566 BR Millingen a/d Rijn
    The Netherlands@{ui}
You can also find me when I am logged in, by entering:
    @{i}finger [e-mail]@{ui}
This will tell you on which machine I'm working currently. To "talk" to me, enter
    @{i}talk (or ntalk) doomen@machinename@{ui}
@ENDNODE
@NODE "AUTHOR" "XToolBox - About The Author"
@NEXT "THANKS"
@PREV "BUGREPORT"
@TOC "MAIN"
@{b}ABOUT THE AUTHOR
----------------@{ub}
My name is Dennis Doomen and I am a 22 year old Dutch student in his last year
of trying to get his degree and becoming an Electronic Engineer. This course
consists of several directions and I have chosen for Computer Technology because
that interests me the most. Therefore I should have chosen to study Informatics
instead (software engineering).
I started my program career when the first C64 came out and I got the Power
Cartridge which allowed me to program in assembly. On that machine I created
some demos and a very fast formattingtool called SuperFormat. All of that using
the alias @{i}Cyberdyne@{ui}. The last thing I did was trying to create a C64
version of the popular Amiga program SoundTracker (yes, a friend of mine got one
of them).
A short time later I got myself my first Amiga, the A500 (1.2) with 1MB memory, 2
external drives (I still have them next to my A1200) and a 1084 colourmonitor.
The programmingstuff started when I purchased @{b}AsmOne@{ub} and a lot of
documentation. However, I did not release any software because it was either for
personal use or I did not finish it at all. The only thing I finished, was a
bootmenu for my utility disks which included a lot of copper work and a nice
scrolling area controlled by the mouse. As a matter of fact I still do have it
and it works too (except the scroller, it runs to fast). I released it using the
alias @{i}Xyborg@{ui}.
I now am the proud owner of a 33MHz 68030MMU equiped Amiga 1200 with a 28MHz
68881 FPU, 4MB Fast memory, a 130MB harddisk and a MicroVitec 1438 Multiscan
monitor running a 896x600 WorkBench screen with 16 colours. As soon as @{b}Amiga
Technologies@{ub} release a new Amiga (RISC?) I will get it. I will surely not get
myself any Intel based machines (I have these at school and I hate to work
with them). I love my machine and I'm still able to impress all of the PC-freaks I
know, so long live the Amiga and good luck to Amiga Technologies. But these days
my live is quite filled up with tasks like studying, girls, going out and listening
to German Rave music. Therefore I don't have a lot of spare time to put myself in
front of my machine, which is the reason that I did not produce any reasonable things
till now. Although I have put down a lot of C-code during my trainingperiod at
Digital Equipment Corporation in Nijmegen, the Netherlands.
@ENDNODE
@NODE "THANKS" "XToolBox - Thanks To"
@NEXT "HISTORY"
@PREV "AUTHOR"
@TOC "MAIN"
@{b}THANKS
------@{ub}
Thanks go to the following people:
    - @{b}Nico Francois@{ub}, for his excellent Reqtools library.
    - All people who answered my questions on USENET.
    - And especially to a guy who helped me with the BOOPSI stuff, I couldn't
      recall his name, because I accidently killed my mailbox. Sorry for that,
      but you know who you are.
@ENDNODE
@NODE "HISTORY" "XToolBox - History"
@NEXT "TODO"
@PREV "THANKS"
@TOC "MAIN"
@{b}HISTORY
-------@{ub}
29-10-95  v1.1  - Added new colordefinition @{"keywords" LINK "GETTINGSTARTED"}.
27-10-95  v1.02 - BUGFIX: Moved the SystemTags() function out of the GetMsg..ReplyMsg
                  loop. Hopefully does not crash anymore (still did).
25-10-95  v1.01 - @{i}XToolBox@{ui} will open by default "s:XToolBox.menu", if no menufile
                  was supplied on the commandline
                - BUGFIX: Replaced Execute() with SystemTags(). It seems that no files
                  crash anymore (I hope!)
@ENDNODE
@NODE "TODO" "XToolBox - To Do"
@PREV "THANKS"
@TOC "MAIN"
@{b}FUTURE PLANS
------------@{ub}
- Probably a preferences program, although I find it quite easy to use a text
  editor.
- PUBSCREEN command line keyword that specifies the public screen to open the
  window on.
- XWindows like windowclass that contains sizegadgets in all 8 directions.
- Option to change the way the menu is opened (such as centered over the
  menubutton, or above it)
@ENDNODE